CD Exchange/CD Exchange - Volume 1.iso/utils/misc/intuimake/intuimake.doc

Text File | 1993-12-11 | 18.0 KB | 533 lines

                              IntuiMake v1.2

                 © 1993 Björn E. Trost and Dirk O. Remmelt.



i. Rights and duties of the authors

   IntuiMake v1.2 was created and tested with the biggest care possible.
   Nevertheless, bugs in the program itself and bugs in programs created
   with IntuiMake can't be locked out. The authors can't be made liable
   for such bugs.



ii. Rights and duties of the user

   IntuiMake is a tool for developers, created with the intention of
   building complex projects, with an easy to use graphics user interface.
   No further knowledge about conventional makes is needed, because
   Intuimake does not deal with script files or things like that.

   Intuimake is intended to be copied freely as long as the price of the
   disk is not more than $6, DM 5.- or the equivalent in any other
   currency. If you like to include IntuiMake in a Public Domain series,
   please send a copy of your finished disk.

   IntuiMake must not be recompiled or changed in any form. This relates
   especially to copyright messages and versionnumbers.

   IntuiMake is no shareware, but it is possible to register. Registered
   users get updates, a printed documentation set with TeX and a good
   support. A register card can be found in the file `Register.txt' in
   this package. Interested users can print it out and send it to me.

   Of course you can write to me without being registered. If you want
   reply, please send an international postal coupon.



iii. Contents of this package

   This software package should include the following files:

   · IntuiMake:               The executable program.
   · IntuiMake.anl:           German documentation.
   · IntuiMake.doc:           This documentation.
   · NewlookMake:             A special version of IntuiMake.
   · Register.txt:            Register card.
   · Registrierkarte.txt:     German register card
   · example/first.c
   · example/first_protos.h
   · example/headerfile.h
   · example/makefile
   · example/main.c
   · example/second.c
   · example/second_protos.h
   · example/test
   · example/obj/first.o
   · example/obj/main.o
   · example/obj/second.o



1. The purpose of a make

   A make is a tool for compiling a program, which consists of several
   modules, in a comfortable way. Especially the compilation of one
   or more modules if a headerfile has changed, should be made automatically.

   The version 1.2 of IntuiMake deals only with the Manx Aztec compiler.



2. Starting, needed files, ...


   IntuiMake needs OS2.0 and the asl-library in LIBS:. By default, the
   makefile is created as `makefile' in the actual directoy.

   IntuiMake should be started from the CLI/Shell with <run IntuiMake>.
   A filename of a makefile can be specified: <run IntuiMake mymakefile>.

   After starting, IntuiMake opens a window which is draggable and
   sizeable. The default settings are loaded and IntuiMake is ready.

   It is recommended, not to start IntuiMake without a CLI/shell, because
   the messages of the compiler and the linker are not redirected. Always
   use a CLI/Shell and IntuiMake together. Fortunately the Amiga can
   multitask...



3. The screen after starting

   After starting and loading the makefile the main window opens itself.
   The biggest part is covered with the listview gadget. It contains all
   modules which belong to the program which should be created.

   Below are the gadgets for starting the compilation, for starting an
   editor and for running and debugging the program.

   In the right are string gadgets for defines which are to be set or not,
   name of the files to be created, versionnumber and a switch for
   activating the debug information.

   The window can be sized and positioned on the screen. These dimensions
   are saved in the makefile.



4. The menus

4.1 Project

4.1.1 Save makefile
      Select this for saving the current makefile. The filename is
      `makefile' or the specified name on startup.
4.1.2 Save makefile as ...
      Sometimes it is useful to deal with more than one makefile. With the
      ASL filerequester a filename for the makefile can be chosen.
4.1.3 Load makefile ...
      For loading a makefile on runtime, this can be selected. The ASL
      filerequester appears and the makefile can be chosen.
4.1.4 Delete objectfiles ...
      The purpose of a make is, making as much as possible automatically.
      But there are several things which force a module to be compiled
      what IntuiMake does not recognize. This could be the copying of an
      older module to the actuals. To force IntuiMake compile this
      module, the object file (*.o) should be deleted. This can be done
      with the ASL filerequester and multiselection (holding the shift key
      pressed).
4.1.5 Edit preferences ...
      In the preferences window many options can be selected:
4.1.5.1 Comparing
      IntuiMake offers the possibility of comparing two sets of modules,
      e.g. for recognizing differents to an older version. For that,
      the two paths of the modules must be given. The file which is
      created must be specified in the `output' string gadget.
4.1.5.2 Scanning
      The automatic search for dependancies can be made faster by
      specifying a string (in remarks) after the `#include' commands.
      This string can be specified with `EndString'. If also the
      beginning of the `#include' statements should be recognized,
      `BeginString' must contain the string which signals the
      beginning of the `#include's. If these strings should be used can
      be declared for C and assembler modules.
      The cycle gadgets for the syntax of the `#include' statements
      should only be used, if other compilers or assemblers than the
      Aztec are used.
      In future versions IntuiMake should be completely independent of the
      compiler and should be programmable.
4.1.5.3 Paths
      With the cycle gadget is for chosing, if an executable program or a
      linker library should be created. If a linker library should be
      created, the tools `Lb' and `Ord', both supported by Manx, must
      be in the actual path.
      In the main window a module can be edited by clicking on `Edit'. For
      that, the desired editor, e.g. `Ed' must be specified in the string
      gadget `Editor'.
      If a precompiled headerfile is used, it must be declared in the
      string gadget `-hi file'. Should the headerfile be used for
      compilation, the compiler option `-hi' must be activated in the
      options window.
      For archiving the modules, headerfiles and the makefile, the archive
      name must be declared in the `Archive' gadget.
      The path in which the modules can be found should be specified in the
      `Sourcecode' gadget. The object files which are created need not to
      be in that path. They can stand anywhere. The path for them can be
      specified in `Objectcode'.
4.1.6 Edit linkeroptions ...
      Here the options for the Aztec linker are to be declared. They can
      be found in the Aztec manual. `Additional modules' stands for all
      oject files or libraries which are not declared as modules, e.g.
      `-lmf -lc'.
4.1.7 About ...
      A requester, created with MaxonPAINT, appears.
4.1.8 Quit
      Used for exiting IntuiMake.


4.2 Action

4.2.1 Make ...
      Starts the compiling and linking. A window opens, in which the
      module, which is to be compiled, is shown. With the close gadget
      compiling can be canceled. With the gadget `Edit' the actual module
      can be edited. `Retry' starts the compilation again. `Next' skips
      the module and compiles the next one. `Make' starts again with all
      modules.
4.2.2 Edit
      Starts the editor specified in the preferences. The editor can be
      started with double clicking the module in the listview gadget, too.
4.2.3 Run
      Starts the created program.
4.2.4 Debug
      Starts the debugger `sdb'.

      The menuitems listed above can also be activated by the gadgets below
      the listview gadget, which is faster.



4.3 Modules
      Intuimake handles C modules and assembler modules. Assembler modules
      should have the postfix `.asm'.

4.3.1 Insert modules...
      With the ASL filerequester the modules, which belong to the program,
      can be declared. Multiselection with the shift key is supported.
      New modules can be added at any time.
4.3.2 Delete module
      The actual module is deleted by selecting this.
4.3.3 Scan module
      IntuiMake offers the possibility of recognizing dependable
      headerfiles. Doing this, the actual module is scanned for
      `#include"'. All headerfiles are recognized recursively, as long as
      all dependancies are recognized.
      To force scanning be more faster, scanning can be canceled if the
      declared string in the preferences is found. This is especially
      useful at larger modules. The string should be set below the last
      `#include' statement.
4.3.4 Scan all modules
      All modules are scanned for includes. Canceling is done by clicking
      the close gadget.
4.3.5 Compare set of modules
      If two or more programmers develop one project, the modules must
      be joined together. IntuiMake offers the possibility of comparing
      two sets for differences. The tool `Diff', which is
      shipped with the compiler, is called. In the preferences the two
      paths and the file in which the changes are written, must be
      declared.
4.3.6 Archive set of modules
      With the tool `Lha' by Stefan Boberg all modules, headerfiles and the
      makefile are archived. The name of the archive must be specified in
      the preferences.
4.3.7 Edit options
      For selecting the compiler or assembler options for each module,
      this menuitem must be selected. Five default settings, which can
      be programmed freely and affect alle modules, and one custum
      setting, which is different for each module, can be set.
      For setting the default options for one or more modules, `As default'
      should be selected after setting the options.



5. Defines

     Conventionally, symbols or defines can be transmitted to the compiler
     via the -d option. Up to five selectable defines can be declared in
     the string gadgets in the right half of the main window. The checkbox
     gadget left of the stringgadget selects the defines or not. This is
     useful in statements like these:

        #ifdef DEMO
               Save ();
        #else
               puts ("Demoversion!");
        #endif



6. Creating a project

     In this section the configuration of IntuiMake and the working with it
     shall be described. For that, the package includes an example project,
     which consists of three modules which are linked together.

6.1 An example

     Here are the modules:


        /* main.c
        **
        **
        */

        #include "first_protos.h"
        #include "second_protos.h"
        /* SCAN_END */

        void main (void)
        {
          Test1 ("Test it:", 1);
          Test2 ("Just do it:");
        }




        /* headerfile.h
        **
        ** SCAN_END
        */

        struct MyStruct
        {
          int  a;
          long b;
        };




        /* first.c
        **
        **
        */

        #include "headerfile.h"
        /* SCAN_END */

        void Test1 (char *message, long var)
        {
          struct MyStruct mystruct = {1, 2L};

          printf ("%s %d\n%d\n%d\n", message, mystruct.a, mystruct.b, var);

        }




        /* second.c
        **
        **
        */

        #include "headerfile.h"
        /* SCAN_END */

        void Test2 (char *message)
        {
          struct MyStruct mystruct = {3, 4L};

          printf ("%s %d\n%d\n", message, mystruct.a, mystruct.b);
        }




        /* first_protos.h
        **
        ** SCAN_END
        */

        void Test1 (char *message, long var);




        /* second_protos.h
        **
        ** SCAN_END
        */

        void Test2 (char *message);


     In `headerfile.h' a structure `MyStruct' is declared, which is used in
     the modules `first' and `second' and must therefor be included. `main'
     does not need this structure. It only needs the prototyp declarations
     for `Test1' and `Test2'. This means, that `first_protos.h' and
     `second_protos.h' must be included from `main.c'.

     With these informations all dependancies are clear. If one of the
     files others depend on, change, all dependable files must be compiled.
     Here is the scheme, but do not worry: This is only done for
     clarity.

     (a -----> b means, that b depends on a.}


            first_protos.h -----> main.c <----- second_protos.h



            first.c <----- headerfile.h -----> second.c



     If the function `Test1' is changed into

               void Test1 (char *message1, short var)

     the file `first_protos.h' must be changed, too. This also causes
     that `main.c' must be compiled because the calling of `Test1'
     has changed. `Second.c' need not be compiled.

     If the structure `MyStruct' is changed in a way like that:

               struct MyStruct
               {
                 short a;
                 long b;
               };

     `first.c' and `second.c' must be compiled because both modules work
     with it. `main.c' does not need this structure and needs not to be
     compiled.

     This should be a short introduction into dependancies. But as I said
     before: Do not worry, this knowledge is not needed because IntuiMake
     has it!




6.2 The settings for the example

    For the creation of an executable program out of the sourcecode some
    things must be done first, which are described here:

    First, IntuiMake must be started: <Intuimake'> or <run IntuiMake>

    After the successfull starting, the modules must be included. For
    that, the menuitem `Modules/Insert modules ...' must be selected.
    The ASL filerequester appears and the modules can be added by
    holding the shift key pressed and selecting the modules `first.c',
    `second.c' and `main.c'. The headerfiles and prototyp declarations
    must not be selected.

    The selected files appear in the listview gadget in alphabetical
    order.

    Next, the compiler options for each module are to be declared.
    The desired module and the menuitem `Module/Edit options' must be
    selected. A window with all compiler options supported by the Aztec
    compiled appears.

    With the cycle gadget one out of five default settings or one custom
    setting can be chosen. The defaults are useful if the same options
    are used for different modules. The options should be set as desired,
    after that, `As default' must be selected. The options are saved and
    used for all other modules which use the same default settings.

    If the options are declared, the version string of the program, e.g.
    `1.2' should be set. IntuiMake creates the version string as recommended
    by Commdore.

    Below the name of the program to be created should be set.

    Next the window for the linker options should be opened with
    `Project/Edit linker options ...'. `Additional modules' should be set
    to `-lc' because the l-library is needed.

    At last, the compiling is started with `Action/Make'. A window opens,
    in which the amount of modules, which are already compiled, is
    displayed. If an error occurs, the module can be corrected by clicking
    `Edit'. `Retry' compiles the module again.

    After a successfull compilation and linkage, the program can be started
    via `Run'.


7. Why must a module be compiled?

   Following a list of events which force the compilation of a module:

   · An object file does not exist.
   · The module was changed.
   · A headerfile, which the module depends on, was changed.
   · The state of a define has changed, and the define is used in the
     module.



I. Credits

   No program without credits: First we would like to thank Commodore
   Business Machines Inc. and Commodore Büromaschinen GmbH for lot of
   uncounted jokes they made. Thank you, Commodore.

   Further we would like to thank Manx Software Systems fo delivering a
   non-functioning make and a non-existing environment. Thank you, Manx.

   But enough of the cynicisme, a big Thank You to Maxon Computer, Eschborn
   Germany, for an examplary developer support. Thank you, Maxon.



II. I like that ol' time rock and roll ...


   Great acoustic performances: · Eric Clapton: Unplugged
                                · Bruce Sptringsteen: (Un)plugged
                                · Neil Young: Unplugged
                                · Rod Stewart: Unplugged and seated

   Great electric performances: · Emerson, Lake & Palmer: Live at the
                                                          Royal Albert Hall
                                · Rush: Exit...stage left
                                · Deep Purple: Made in Japan
                                · Toto: Absolutely live

   Great new albums:            · Deep purple: The battle rages on
                                · Rush: Counterparts
                                · Def Leppard: Retro active
                                · Dio: Strange highways

   Great concerts in Europe:    · Deep Purple: The battle rages on,
                                               Oct 1993
                                · Ronnie James Dio: Strange highways,
                                                    Dec 1993
                                · Robert Plant: Fate of nations,
                                                Dec 1993
                                · Pink Floyd: *************
                                              Aug 1994



III. Epilogue

   If you want to contact us, please write to


                              Bjoern E. Trost
                         Auf dem Baennjerrueck 39
                           67663 Kaiserslautern
                                  Germany

                                    or

                              Dirk O. Remmelt
                             Lutrinastrasse 11
                           67655 Kaiserslautern
                                  Germany



  Kaiserslautern, in November of 1993